home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / xwindows / demos / xfract_1.z / xfract_1 / xfractint-1.06 / hc.doc < prev    next >
Text File  |  1992-09-28  |  17KB  |  535 lines
  1.  
  2. ... First version documentation is followed by additional notes
  3. ... for features added in subsequent versions.
  4.  
  5.  
  6.            FRACTINT Help Compiler Source File Format
  7.  
  8.  
  9.  
  10. 0. Contents
  11.  
  12.     1.0     Help compiler input/output.
  13.     1.1       The source input file.
  14.     1.2       The header (.H) output file.
  15.     1.3       The binary (.HLP) output file.
  16.     2.0     Source (.SRC) file format.
  17.     2.1       Comments.
  18.     2.2       Defining the output filenames.
  19.     2.3       Defining the help file version.
  20.     2.4.0     Help topics.
  21.     2.4.1    Starting a help topic.
  22.     2.4.2.0    The help text.
  23.     2.4.2.1      Special characters.
  24.     2.4.3    Starting another page.
  25.     2.5.0     Labels.
  26.     2.5.1    The help index label (HELP_INDEX).
  27.     2.5.2    Private labels.
  28.     2.6.0     Hot-links.
  29.     2.6.1    Special hot-links.
  30.     2.7       Tables.
  31.  
  32.  
  33. 1.0 Help compiler input/output.
  34.  
  35.     The Help Compiler converts a source file into two output files: a "C"
  36.   header file which is #included in FRACTINT and a binary file used at run-
  37.   time.
  38.  
  39.  
  40. 1.1 The source input file.
  41.  
  42.     The Help compiler takes as input a help source file (.SRC).  See x.x.x
  43.   for the .SRC file format.  HELP.SRC is FRACTINT's help file source.
  44.  
  45.  
  46. 1.2 The header (.H) output file.
  47.  
  48.     The header (.H) file contains a #define macro for each non-private label
  49.   (see 2.5.0) and for the help file version (see 2.3).    The .H file is
  50.   included in FRACTINT and the macros are used to set the current help mode.
  51.  
  52.     The Help Compiler will only modify the .H file when a non-private label
  53.   (see 2.5.0) is added or deleted or when the help file version (see 2.3)
  54.   is changed.  This minimizes the times when FRACTINT will need to be re-
  55.   compiled.  However, when the Help Compiler does modify the .H file it is
  56.   necessary to re-compile FRACTINT.
  57.  
  58.   In FRACTINT this file is named HELPDEFS.H
  59.  
  60. 1.3 The binary (.HLP) output file.
  61.  
  62.     The .HLP file is the binary file where compiled help informnation is
  63.   stored.  See HC.C and HELP.C if you're interested in the file format.  In
  64.   FRACTINT the file is named FRACTINT.HLP.  This file may be appended to
  65.   FRACTINT.EXE for distribution, see the Help Compiler command-line help
  66.   (type "HC" at the DOS prompt) more info.
  67.  
  68.  
  69. 2.0 Source (.SRC) file format.
  70.  
  71.     The source file defines output files, help file version, topics, labels
  72.   and hypertext-style hot-links with commands and hot-links.  Commands start
  73.   with a tilde ('~') in the first column of a line and continue to the end
  74.   of the line.    Hot-links, defined within the text, are surrounded by curly-
  75.   braces ('{' and '}').  Comment lines, which may appear anywhere in the
  76.   file, start with a semicolon (';') in the first column and continue to
  77.   the end of the line.
  78.  
  79.  
  80. 2.1 Comments.
  81.  
  82.     Any line starting with a semicolon (;) is a comment.  The comment
  83.   continues to the end of the line and may appear anywhere in the file.
  84.   The semicolon must be in the first column of the line.
  85.  
  86.  
  87. 2.2 Defining the output filenames.
  88.  
  89.     The output filenames are defined in the source file by the following
  90.   commands:
  91.  
  92.     ~HdrFile=H_FILE
  93.     ~HlpFile=HLP_FILE
  94.  
  95.   H_FILE is the .H filename and HLP_FILE is the .HLP filename.    These
  96.   commands must appear before the first topic.
  97.  
  98.  
  99. 2.3 Defining the help file version.
  100.  
  101.     The help file version number is stored in a special #define in the .H
  102.   file (named HELP_VERSION) and stored in the .HLP file header.  If the
  103.   version number in HELP_VERSION does not match the version in the .HLP file
  104.   the file will not be used.  This is mainly to make sure FRACTINT doesn't
  105.   try to read a help file other than the one the .EXE is expecting.  To
  106.   define the help version:
  107.  
  108.     ~Version=nnn
  109.  
  110.   Where nnn is a positive decimal version number.  (Suggested format is 100
  111.   for version 1.00, 150 for version 1.50, etc.)  This command must appear
  112.   before the first help topic.    -1 will be used if the version is not defined
  113.   in the .SRC file.
  114.  
  115.  
  116. 2.4.0 Help topics.
  117.  
  118.     The help topics come after the HdrFile=, HlpFile= and Version= commands
  119.   and continue until end-of-file.
  120.  
  121.  
  122. 2.4.1 Starting a help topic.
  123.  
  124.   To start a new help topic use the following format:
  125.  
  126.     ~Topic=TITLE
  127.  
  128.   "~Topic=" is the command to start a topic and TITLE is the text to display
  129.   at the top of each page.  The title continues to the '\n' and may contain
  130.   up to 65 characters.
  131.  
  132.     In the example:
  133.  
  134.     ~Title=Command Keys available while in Display Mode
  135.  
  136.   "Command Keys avail..." is the TITLE which would displayed at the top of
  137.   each page.
  138.  
  139.  
  140. 2.4.2.0 The help text.
  141.  
  142.     The help text for each topic can be several pages long. Each page is 22
  143.   rows by 78 columns.  The first and last rows should be blank for the best
  144.   appearance.
  145.  
  146.  
  147. 2.4.2.1 Special characters.
  148.  
  149.     To insert reserved characters (like ';', '~', '\' and '{') into the help
  150.   text precede the character with a backslash ('\').  To insert any character
  151.   (except null) into the text follow a backslash with a decimal (not hex
  152.   or octal) ASCII character code.  For example:
  153.  
  154.     \~  - puts a tilde in the text.
  155.     \24 - places an up-arrow in the text.
  156.  
  157.  
  158. 2.4.3 Starting another page.
  159.  
  160.     To start a new page in the same topic put two tildes (~~) at the start
  161.   of a line.  No other text is allowed on the line.  Each page can be up to
  162.   22 lines long.  (The Help Compiler will warn you if any page gets longer
  163.   than 22 lines.)  For the best appearance the first and last lines should
  164.   be blank.
  165.  
  166.  
  167. 2.5.0 Labels.
  168.  
  169.     A label is a name which in used to refer to a help topic.  A label is
  170.   used in hot-links or in FRACTINT for context-sensitive help.    When help
  171.   goes to a label (when a hot-link is selected or context-sensitive help
  172.   is called from FRACTINT) it goes to the page of the topic where the label
  173.   was defined.
  174.  
  175.     To define a label for a topic insert the following command into the
  176.   topic's text:
  177.  
  178.     ~(NAME)
  179.  
  180.   NAME is the name of the label.  The name follows "C"-style conventions
  181.   for variable names.  Case is significant.  The label should start at the
  182.   beginning of a line and have no text following it on the line.  The line
  183.   line will not appear in the help text.
  184.  
  185.     For example, if this line:
  186.  
  187.   ~(HELPPLASMA)
  188.  
  189.   was placed in page three of a topic using it in a hot-link (see 2.6.0)
  190.   or as context-sensitive help would "go to" page three of that topic.  The
  191.   user would then be free to page up and down through the entire topic.
  192.  
  193.     Each topic must have at least one label otherwise it could not be
  194.   referred to.
  195.  
  196.  
  197. 2.5.1 The help index label (HELP_INDEX).
  198.  
  199.     When the user wants to go to the "help index" (by pressing F1 while
  200.   in help) help will go to a special label named "HELP_INDEX".  Other than
  201.   the requirement that it be in every .SRC file you may treat it as any
  202.   other label.    It can be used in links or as context-sensitive help.
  203.  
  204.  
  205. 2.5.2 Private labels.
  206.  
  207.     A private label is a label which is local to the help file.  It can be
  208.   used in hot-links but cannot be used as context-sensitive help.  A private
  209.   label is a label with an "at sign" ('@') as the first character of its
  210.   name.  The "at sign" is part of the name.  In the example:
  211.  
  212.     ~(@HELPPLASMA)
  213.  
  214.   "@HELPPLASMA" is a private label.
  215.  
  216.     Private labels are not included in the .H file so you may add or delete
  217.   private labels without re-compiling FRACTINT.  Each non-private label
  218.   takes up some memory (4 bytes) in FRACTINT so it's best to use private
  219.   labels whenever possible.  Use private labels except when you want to use
  220.   the label as context-sensitive help.
  221.  
  222.  
  223. 2.6.0 Hot-links.
  224.  
  225.     A hypertext-style hot-link to a label can appear anywhere in the help
  226.     text.  To define a hot-link use the following syntax:
  227.  
  228.     {LABEL TEXT}
  229.  
  230.   LABEL is the label to link to and TEXT is the text that will be highlighted.
  231.   Only the TEXT field will appear on the help screen.  No blanks are allowed
  232.   before the LABEL.  In the sample hot-link:
  233.  
  234.     {HELPMAIN Command Keys in display mode}
  235.  
  236.   "HELPMAIN" is the LABEL and "Command keys in display mode" is the
  237.   TEXT to will be hightlighted.
  238.  
  239.  
  240. 2.6.1 Special hot-links.
  241.  
  242.     In addition to normal hot-links to labels "special" links to custom
  243.   functions (built into HELP.C) are allowed.  These hot-links have a
  244.   negative number (-2..) in plac